package com.feature50.clarity.formui;

import com.feature50.util.SwingUtils;
import com.feature50.clarity.FormException;

import javax.swing.JComponent;

public abstract class FormUI {
    /**
     * Retrieves the component at the top of this component's hierarchy.
     *
     * @return
     * @throws com.feature50.clarity.FormException
     */
    public abstract JComponent getRootComponent() throws FormException;

    /**
     * Retrieves a component from the run-time Swing component hierarchy based on the component's name.  While the
     * implementation of this class could use any mechanism for mapping Swing components to a <code>String</code> name,
     * it is strongly recommended that the mapping be based on {@link javax.swing.JComponent}'s <code>name</code> property.
     * <br>
     * The default implementation of this method walks the component hierarchy from the root component down. Implementers
     * may replace it with a higher-performance version if desired.
     *
     * @param name
     * @return the references <code>JComponent</code>, or <code>null</code> if no such reference could be found.
     */
    public JComponent getComponent(String name) {
        return SwingUtils.getComponentByName(getRootComponent(), name);
    }
}